
# Simple personal blog framework

This is repository serves a two-fold purpose: firstly, as my personal blog
generator and framework; and, secondly, as my blog itself. These goals are, at
the same time, both necessarily interlinked and completely separate.

In one hand, this is a framework. It has scripts for page generation, its highly
opionated on its syntax and has tools for actually serving the pages themselves.
On the other, its a collection of pages on a variety of topics of my own
personal interest, written within this framework. These pages serve as both
testing input for the framework and as the blog itself when generated.

The result is an hybrid of a blog focused framework and of the personal blog
itself. A chimera of tools and content both personal and general.  The programs
might help you  create a site just like mine, but, even better, might set you on
your way to create it whitin your own conceptions of what is good design. Beyond
it even, might propel you forward on writing your own programs for personal
use, giving birth to a chimera that is at the same time different and perfectly
alike mine.

# The framework

The framework touches on three major parts:

1. Writing the pages. Which on touch the macros, the HTML style and the
   directory structure
2. Generating the site, done via build scripts
3. The web server. Which serves the site proper.

We will go through these in order.

## Writing the pages

The process of writing the pages involves three steps: application of proper
HTML writing style, the macros in use and the type of the page. None of them
are particular complex steps.

### Conventions of writing

Firstly, while there is some quality of life features implemented via M4 macros
or directly in the generation script, the bulk of the web page remains normal
HTML, albeit in its shortform, that is, HTML that takes advantage of optional
tags and proper indentation.

The common practice of being verbose when writing HTML tags, while normally
correct for most enviroments, is simply inappropriate for the common writer.
Much better is, instead, to write HTML with a syntax that more closely resembles
Roff programs, which is one that mostly eschews indendation and describes the
formatting on the beginning of the previous line. For example:

```text
<title>A simple HTML page</title>
<h1>A simple HTML page</h1>

<p>
A brief paragraph, describing something of great importance.

<p>
Here is a list for you:

<ul>
<li>First item.
<li>Second item.
</ul>
```

This is far simpler and more digestible than being fully verbose. We can go
further and omit the `title` tag, since it would be generated by our build
script from the `h1` tag. This is done because all pages usually have only a
single level heading anyway.

### Directory structure

Now, the placement of the files vary according to their type. There are three
types of files in the site's directory structure: pages, posts and parts files.

Pages (`pages.html`) files compose files that are their own thing. Usually a
about page or the site map. Posts (`post.html`) refer to the blog posts, which
usually fall within some category and, lastly, the parts (`part.html`) are files
that are included, via the M4 `include` macro, in other files.

### Macros

Currently supported, is the hability of having a link array for all the links in
your pages. For example, if you add the following line to the macro file:

```text
links.push(`my_page', `www.mypage.com')
```

You can later reference the link using `links.fetch`:

```text
<a href="links.fetch(my_page)">video</a>.
```

This is added both for the convenience factor, but also it makes reading and
editing the source code of pages more confortable.

Another simple convenience feature is the `<todo>` element, which gets expanded
to a paragraph of `class="todo"` for which is styled via CSS.

```text
<todo>
A todo paragraph
```

Lastly, and perhaps the most useful of the macros, is the `include` macro. For
example:

```text
include(page.html)
```

Will include a file named `page.html` at whatever part this file is
named.

For now, syntactically, these are the only features supported, but probably more
will come in due time.

## Why not markdown?

A probably common question being leveraged right now is: why not just use
Markdown?

Its a question not without merit. After all, Markdown is a well established
format, praised by writer and developer alike. There is night textbox in in the
web that doesn't support at least a subset of it. Hell, even this README is
being written in Markdown. Why, then, not just bite the bullet and use it?

Well there are a few reasons.

For starters, Markdown syntax is deceptfully simple. While it prouds itself
in being source readable code, findings its origins in the conventions adopted in
the USENET of old, Markdown simply its not enough for the use cases that go
beyond its roots. Its a language born out of forum posts, which require
only a subset of features from most markup languages, basically: headings,
bullet lists (numbered or unumbered), emphasis and quoting.

This particular set can cover most users needs of expressing. A great amount of
texts, both ancient and modern, won't need much more than that. But many texts
will end up requiring more than is guaranteed by the spec, especially those
developed by programmers. Its of no surprise the amount of Markdown
extensions, flavors and even conventions that one can find, each of them
offering an alternative or a solution to some common problem that Markdown is
simply not cabaple to handle. What is often forgotten is that its incapability
does not stem from oversight or error, but from its very *design*. Markdown
mimics the etiquette of online forums and it excels in this particular use case,
but anything past this requires a great deal more of work, usually calling for
more extensions or the behaviours of specific compilers. The saving grace of
Markdown, and probably the reason why it has stuck around for so long, is due to
the recurrence of this basic case. The bulk of most of written text will be just
what it offers: headings, quotes, emphasis and bullet lists. Most of what
I write falls within this category, the issue arises whenever I want to do
something more. The usual answer to this is: Markdown is merely a superset of
HTML, at any given moment you can drop back to it. This response has its shade
shade of truth, but is not without its flaws.

In my view, Markdown greatest strength lies in its ease of use. Its simple to
write and to read it, there is probably no other markup that can be truly
considered source readable. But as features and further structures are
superimposed on its uncomplicated core, more and more it resembles most markup
around. If I have to drop down to HTML recurrently to do what I want, or have to
cave to various Markdown implementations and extensions, for one, I'm not using
Markdown anymore; and, for other, I *rather*  not use Markdown anymore. In this
scenario, the source has become as readable and as editable as any other markup
language, but now with twice the hassle of setting it up. In this situation, I
see no reason to not just use HTML while taking advantages of its optional
tags and avoiding indentation whenever possible. The end result is a slightly
more verbose Markdown with none of its drawbacks, plus with the removal of all the
convertion infrastructure.

Unfortunately, whether we like it or not, the marked up source of our documents
can only be as readable as the use case demands it. If there are certain markup
languages considered more or less source readable than others, it usually falls
down to a matter of taste, assuming they have support for equal things. Markdown
was especial that it stood alone as the *actually* source readable markup
because it barely even looked like markup, its simplicity even evident by the
layman's adoption of it. This was my initial reason for using it, I wanted
source code that actually as readble, or as close as it could be, to the
generated document.

Alas, two things eventually became clear for me: first, no matter how readable
the source, nothing beats the formatted document; second, Markdown, when coerced
for the uses of the programmer and not for those of the forum contributor,
becomes akin to HTML, but with parts clearly forcefully bolted on top.

That all said, I still think Markdown has its place and value, especially where
it has culturally become the norm (i.e forum posts, project's READMEs, etc). The
reasoning presented here is merely to justify my preference for this framework
and for my own posts going forward, since I had initially attempted to utilize
Markdown for this purpose, but wasn't satisfied with the result.

# Generating and serving the site

To build the site as its stands, merely run `make` at the project's root. To run
it, just type `make run`.

The build script will generate the appropriate site with metadata and
properly nested table of contents for each of the posts.

For the particular case of a page named `index.page.html`, the script will
create a site map mimicking the structure of the `posts` directory. You can
customize the domain name and port number by passing the `DOMAIN` and `PORT`
variables to `make`.

# Considerations for general use

This is still a work in progress and, as it stands, it clearly has a lot of its
parts hardcoded for my own use. And, while I do believe into exposing more
functionality for general use, I find it hard to disassociate this project from
my own strange and evolving human idiosyncracies. I rather that you, potential
user, see this hybrid framework-blog as it is and going forward, mostly as a
blueprint or as a source of inspiration. 

While there is complexity here, its far simpler than what, as far as I know, is
usually peddled my the web frameworks. It can be build and maintained by a
single individual, because it doesn't have a lot of moving parts. It only parses
pages, adds stuff to them and serves them. It leverages robust techonlogies that
have been around for a while. Truly, its only as complex as it is due to the fun
I have building it. One could completely remove the build script and simply add
what it does by hand. Through the magic of copy and pasting and templates, very
little time would be truly wasted in comparison to writing it, maintaning, etc.

Ultimately, the tools here don't aspire to be general, to be the best in the
market, to overtake whatever already exists and so on and so forth. They are
just what they appear to be: a passion project from someone throughly interested
not only in writing, but on learning and building the tools that surround the
writing process.
